package module.StoreService;

import common.model.Entity.StoreEntity.Order;
import network.protocol.Response;
import java.util.List;
import java.util.Optional;

/**
 * {@code OrderService} 定义了订单（Order）相关的业务操作接口。
 * <p>
 * 主要提供以下功能：
 * <ul>
 *     <li>根据 ID 或订单号获取订单</li>
 *     <li>获取用户订单、状态订单或全部订单</li>
 *     <li>创建、更新、逻辑删除订单</li>
 *     <li>更新订单状态</li>
 *     <li>统计订单数量（总数或用户订单数）</li>
 * </ul>
 * <p>
 * 所有方法均返回统一封装的 {@link Response} 对象，
 * 调用方可根据该对象判断操作成功与否并获取相关数据。
 */
public interface OrderService {

    /**
     * 根据订单 ID 获取订单。
     *
     * @param id 订单的唯一标识
     * @return 包含订单对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<Order>> getOrderById(long id);

    /**
     * 根据订单号获取订单。
     *
     * @param orderNumber 订单编号
     * @return 包含订单对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<Order>> getOrderByNumber(String orderNumber);

    /**
     * 获取指定用户的所有订单。
     *
     * @param userId 用户的唯一标识
     * @return 包含订单列表的响应对象；
     *         如果没有订单，则返回空列表
     */
    Response<List<Order>> getOrdersByUser(long userId);

    /**
     * 根据订单状态获取所有订单。
     *
     * @param status 订单状态（例如：待支付、已完成、已取消等）
     * @return 包含订单列表的响应对象；
     *         如果没有订单，则返回空列表
     */
    Response<List<Order>> getOrdersByStatus(int status);

    /**
     * 获取指定用户在某一状态下的订单。
     *
     * @param userId 用户的唯一标识
     * @param status 订单状态
     * @return 包含订单列表的响应对象；
     *         如果没有订单，则返回空列表
     */
    Response<List<Order>> getOrdersByUserAndStatus(long userId, int status);

    /**
     * 获取系统中的所有订单。
     *
     * @return 包含订单列表的响应对象；
     *         如果没有订单，则返回空列表
     */
    Response<List<Order>> getAllOrders();

    /**
     * 创建新的订单。
     *
     * @param order 订单实体对象，包含必要的订单信息
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createOrder(Order order);

    /**
     * 更新订单信息。
     *
     * @param order 订单实体对象，必须包含有效的 ID
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateOrder(Order order);

    /**
     * 删除订单（逻辑删除，不会物理移除数据）。
     *
     * @param id 订单的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> deleteOrder(long id);

    /**
     * 更新指定订单的状态。
     *
     * @param orderId 订单的唯一标识
     * @param status  新的订单状态
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateOrderStatus(long orderId, int status);

    /**
     * 获取系统中订单的总数量。
     *
     * @return 包含订单总数的响应对象
     */
    Response<Long> getOrderCount();

    /**
     * 获取指定用户的订单总数量。
     *
     * @param userId 用户的唯一标识
     * @return 包含订单总数的响应对象
     */
    Response<Long> getOrderCountByUser(long userId);
}
